Moved heroku documentation and restructured directories
Dominik Sander
8 changed files with 169 additions and 8 deletions
+ 13
- 5
doc/README.md
@@ -1,11 +1,19 @@ |
||
| 1 | 1 |
# Documentation |
| 2 | 2 |
|
| 3 |
-## User documentation |
|
| 3 |
+## Installation and upgrading |
|
| 4 | 4 |
|
| 5 |
-- [Check out Huginn with Docker](install/docker.md) Run a local Huginn installation using Docker |
|
| 5 |
+### Docker (not recommended for production) |
|
| 6 | 6 |
|
| 7 |
+- [Check out Huginn with Docker](docker/install.md) Run a local Huginn installation using Docker |
|
| 7 | 8 |
|
| 8 |
-## Administrator documentation |
|
| 9 |
+### Manual installation |
|
| 9 | 10 |
|
| 10 |
-- [Install](install/README.md) Requirements, directory structures and installation from source. |
|
| 11 |
-- [Update](update/README.md) Update guides to upgrade your installation. |
|
| 11 |
+Manual installation which will guide through the steps to install Huginn on any Ubuntu 12.04/14.04 or Debian 6/7 server. |
|
| 12 |
+ |
|
| 13 |
+- [Install](manual/README.md) Requirements, directory structures and installation from source. |
|
| 14 |
+- [Update](manual/update.md) Update your installation. |
|
| 15 |
+ |
|
| 16 |
+### Heroku |
|
| 17 |
+ |
|
| 18 |
+- [Deploy to Heroku](heroku/install.md) |
|
| 19 |
+- [Update](heroku/update.md) an existing Heroku deployment |
doc/install/docker.md → doc/docker/install.md
+ 144
- 0
doc/heroku/install.md
@@ -0,0 +1,144 @@ |
||
| 1 |
+## Deploy to Heroku |
|
| 2 |
+ |
|
| 3 |
+### Important things to keep in mind |
|
| 4 |
+ |
|
| 5 |
+* Heroku's [Free plan](https://www.heroku.com/pricing) now requires your application to sleep for at least 6 hours a day, thus the `Hobby` plan is recommended. |
|
| 6 |
+* Heroku's free Postgres plan limits the number of database rows that you can have to 10,000, so you should be sure to set a low event retention schedule for your agents. |
|
| 7 |
+* The `setup_heroku` command points Heroku at a special Procfile (`deployment/heroku/Procfile.heroku`) that is designed to be run on only one Heroku web worker. If you want to run multiple workers, change the Heroku config variable `PROCFILE_PATH` with `heroku config:set PROCFILE_PATH=./Procfile` and switch back to the standard Huginn Procfile configuration. |
|
| 8 |
+ |
|
| 9 |
+### Instructions |
|
| 10 |
+ |
|
| 11 |
+* Install the [Heroku Toolbelt](https://toolbelt.heroku.com/) and then run `heroku login` |
|
| 12 |
+* Go into your huginn directory and run `bundle` |
|
| 13 |
+* Now, run the magic setup wizard: `bin/setup_heroku` |
|
| 14 |
+* That's it! |
|
| 15 |
+* If you make changes, you can re-run `bin/setup_heroku`, or just do `git push heroku master`. |
|
| 16 |
+* Signup for a free [Pingdom](https://www.pingdom.com/free/) account and have it ping your Huginn URL instance on Heroku. This should help keep your Heroku instance awake and watching the world for you. Keep in mind the Heroku's Free plan needs your application to sleep for 6 hours a day. |
|
| 17 |
+ |
|
| 18 |
+ |
|
| 19 |
+### Using your own mail server |
|
| 20 |
+ |
|
| 21 |
+```bash |
|
| 22 |
+# Outgoing email settings. To use Gmail or Google Apps, put your Google Apps domain or gmail.com |
|
| 23 |
+# as the SMTP_DOMAIN and your Gmail username and password as the SMTP_USER_NAME and SMTP_PASSWORD. |
|
| 24 |
+heroku config:set SMTP_DOMAIN=your-domain-here.com |
|
| 25 |
+heroku config:set SMTP_USER_NAME=you@gmail.com |
|
| 26 |
+heroku config:set SMTP_PASSWORD=somepassword |
|
| 27 |
+heroku config:set SMTP_SERVER=smtp.gmail.com |
|
| 28 |
+ |
|
| 29 |
+# The address from which system emails will appear to be sent. |
|
| 30 |
+heroku config:set EMAIL_FROM_ADDRESS=you@gmail.com |
|
| 31 |
+``` |
|
| 32 |
+ |
|
| 33 |
+### Backing up your data |
|
| 34 |
+ |
|
| 35 |
+See: https://devcenter.heroku.com/articles/heroku-postgres-import-export |
|
| 36 |
+ |
|
| 37 |
+### Example output from `bin/setup_heroku` |
|
| 38 |
+ |
|
| 39 |
+``` |
|
| 40 |
+~/projects/oss/huginn (master)$ bin/setup_heroku |
|
| 41 |
+ |
|
| 42 |
+Welcome andrew@example.com! It looks like you're logged into Heroku. |
|
| 43 |
+ |
|
| 44 |
+It looks like you don't have a Heroku app set up yet for this repo. |
|
| 45 |
+You can either exit now and run 'heroku create', or I can do it for you. |
|
| 46 |
+Would you like me to create a Heroku app for you now in this repo? (y/n) y |
|
| 47 |
+Creating radiant-forest-1519... done, stack is cedar |
|
| 48 |
+http://radiant-forest-1519.herokuapp.com/ | git@heroku.com:radiant-forest-1519.git |
|
| 49 |
+Git remote heroku added |
|
| 50 |
+Your Heroku app name is radiant-forest-1519. Is this correct? (y/n) y |
|
| 51 |
+Setting up APP_SECRET_TOKEN... |
|
| 52 |
+Setting BUILDPACK_URL to https://github.com/ddollar/heroku-buildpack-multi.git |
|
| 53 |
+BUILDPACK_URL: https://github.com/ddollar/heroku-buildpack-multi.git |
|
| 54 |
+Setting PROCFILE_PATH to deployment/heroku/Procfile.heroku |
|
| 55 |
+PROCFILE_PATH: deployment/heroku/Procfile.heroku |
|
| 56 |
+Setting ON_HEROKU to true |
|
| 57 |
+Setting FORCE_SSL to true |
|
| 58 |
+Setting DOMAIN to radiant-forest-1519.herokuapp.com |
|
| 59 |
+ |
|
| 60 |
+You need to set an invitation code for your Huginn instance. If you plan to share this instance, you will |
|
| 61 |
+tell this code to anyone who you'd like to invite. If you won't share it, then just set this to something |
|
| 62 |
+that people will not guess. |
|
| 63 |
+What code would you like to use? |
|
| 64 |
+What code would you like to use? something-secret |
|
| 65 |
+Setting INVITATION_CODE to something-secret |
|
| 66 |
+ |
|
| 67 |
+Okay, let's setup outgoing email settings. The simplest solution is to use the free sendgrid Heroku addon. |
|
| 68 |
+If you'd like to use your own server, or your Gmail account, please see .env.example and set |
|
| 69 |
+SMTP_DOMAIN, SMTP_USER_NAME, SMTP_PASSWORD, and SMTP_SERVER with 'heroku config:set'. |
|
| 70 |
+Should I enable the free sendgrid addon? (y/n) y |
|
| 71 |
+Use `heroku addons:docs sendgrid` to view documentation. |
|
| 72 |
+SMTP_SERVER: smtp.sendgrid.net |
|
| 73 |
+SMTP_DOMAIN: heroku.com |
|
| 74 |
+SMTP_USER_NAME: app27830035@heroku.com |
|
| 75 |
+SMTP_PASSWORD: sflajgz0 |
|
| 76 |
+What email address would you like email to appear to be sent from? andrew@example.com |
|
| 77 |
+Setting EMAIL_FROM_ADDRESS to andrew@example.com |
|
| 78 |
+EMAIL_FROM_ADDRESS: andrew@example.com |
|
| 79 |
+ |
|
| 80 |
+Should I push your current branch (master) to heroku? (y/n) y |
|
| 81 |
+This may take a moment... |
|
| 82 |
+Initializing repository, done. |
|
| 83 |
+ |
|
| 84 |
+-----> Fetching custom git buildpack... done |
|
| 85 |
+-----> Multipack app detected |
|
| 86 |
+=====> Downloading Buildpack: https://github.com/cantino/heroku-selectable-procfile.git |
|
| 87 |
+=====> Detected Framework: Selectable Procfile |
|
| 88 |
+-----> Using deployment/heroku/Procfile.heroku as Procfile |
|
| 89 |
+=====> Downloading Buildpack: https://github.com/heroku/heroku-buildpack-ruby.git |
|
| 90 |
+=====> Detected Framework: Ruby |
|
| 91 |
+-----> Compiling Ruby/Rails |
|
| 92 |
+-----> Using Ruby version: ruby-2.0.0 |
|
| 93 |
+-----> Installing dependencies using 1.6.3 |
|
| 94 |
+ Running: bundle install --without development:test --path vendor/bundle --binstubs vendor/bundle/bin -j4 --deployment |
|
| 95 |
+ Fetching source index from https://rubygems.org/ |
|
| 96 |
+ Fetching git://github.com/cantino/twitter-stream.git |
|
| 97 |
+ Installing i18n 0.6.9 |
|
| 98 |
+ Installing rake 10.3.2 |
|
| 99 |
+ Installing minitest 5.3.5 |
|
| 100 |
+ [...gems are installed...] |
|
| 101 |
+ Your bundle is complete! |
|
| 102 |
+ Gems in the groups development and test were not installed. |
|
| 103 |
+ It was installed into ./vendor/bundle |
|
| 104 |
+ Post-install message from httparty: |
|
| 105 |
+ When you HTTParty, you must party hard! |
|
| 106 |
+ Post-install message from rufus-scheduler: |
|
| 107 |
+ Bundle completed (133.85s) |
|
| 108 |
+ Cleaning up the bundler cache. |
|
| 109 |
+-----> Preparing app for Rails asset pipeline |
|
| 110 |
+ Running: rake assets:precompile |
|
| 111 |
+ I, [2014-07-26T20:36:06.069156 #5939] INFO -- : Writing /tmp/build_7b0d30bd-3c35-46dc-b73d-b5f05754d340/public/assets/select2x2-ec4bf2b76c97838b357413d72a2f69cf.png [...] |
|
| 112 |
+ Asset precompilation completed (42.28s) |
|
| 113 |
+ Cleaning assets |
|
| 114 |
+ Running: rake assets:clean |
|
| 115 |
+ |
|
| 116 |
+Using release configuration from last framework (Ruby). |
|
| 117 |
+-----> Discovering process types |
|
| 118 |
+ Procfile declares types -> web |
|
| 119 |
+ Default types for Multipack -> console, rake, worker |
|
| 120 |
+ |
|
| 121 |
+-----> Compressing... done, 45.1MB |
|
| 122 |
+-----> Launching... done, v19 |
|
| 123 |
+ http://radiant-forest-1519.herokuapp.com/ deployed to Heroku |
|
| 124 |
+ |
|
| 125 |
+To git@heroku.com:radiant-forest-1519.git |
|
| 126 |
+ * [new branch] master -> master |
|
| 127 |
+Running database migrations... |
|
| 128 |
+Running `rake db:migrate` attached to terminal... up, run.3341 |
|
| 129 |
+ |
|
| 130 |
+[...migrations run...] |
|
| 131 |
+ |
|
| 132 |
+I can make an admin user on your new Huginn instance and setup some example Agents. |
|
| 133 |
+Should I create a new admin user and some example Agents? (y/n) y |
|
| 134 |
+ |
|
| 135 |
+Okay, what is your email address? andrew@example.com |
|
| 136 |
+And what username would you like to login as? andrew |
|
| 137 |
+Finally, what password would you like to use? |
|
| 138 |
+Just a moment... |
|
| 139 |
+ |
|
| 140 |
+ |
|
| 141 |
+Okay, you should be all set! Visit https://radiant-forest-1519.herokuapp.com and login as 'andrew' with your password. |
|
| 142 |
+ |
|
| 143 |
+Done! |
|
| 144 |
+``` |
+ 9
- 0
doc/heroku/update.md
@@ -0,0 +1,9 @@ |
||
| 1 |
+## Update an existing Heroku deployment |
|
| 2 |
+ |
|
| 3 |
+Once you've run `bin/setup_heroku`, you should have 'cantino/huginn' as a remote in git. (Check with `git remote -v`.) Now, you can update your Heroku installation with the following commands: |
|
| 4 |
+ |
|
| 5 |
+```sh |
|
| 6 |
+git fetch origin |
|
| 7 |
+git merge origin/master |
|
| 8 |
+git push -f heroku master # note: this will wipe out any code changes that only exist on Heroku! |
|
| 9 |
+``` |
+ 2
- 2
doc/install/README.md
@@ -1,5 +1,5 @@ |
||
| 1 |
-# Installation |
|
| 1 |
+# Manual Installation |
|
| 2 | 2 |
|
| 3 | 3 |
- [Requirements](requirements.md) Software and hardware requirements to run the Huginn installation |
| 4 | 4 |
- [Install](installation.md) Installation guide for Ubundu/Debian |
| 5 |
-- [Update](../update/README.md) Update an existing Huginn installation |
|
| 5 |
+- [Update](update.md) Update an existing Huginn installation |
doc/install/installation.md → doc/manual/installation.md
+ 1
- 1
doc/install/requirements.md
@@ -4,7 +4,7 @@ |
||
| 4 | 4 |
|
| 5 | 5 |
### Supported Unix distributions by this guide |
| 6 | 6 |
|
| 7 |
-- Ubuntu (12.04 and 14.04) |
|
| 7 |
+- Ubuntu (14.04 and 12.04) |
|
| 8 | 8 |
- Debian (Jessie and Wheezy) |
| 9 | 9 |
|
| 10 | 10 |
### Unsupported Unix distributions |